home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 …ember: Reference Library / Apple Developer Reference Library (December 1999) (Disk 1).iso / pc / technical documentation / develop / develop issue 28 / develop issue 28 code / merge tools / !readme next >
Encoding:
Text File  |  1996-09-25  |  13.6 KB  |  296 lines
  1. This directory contains the Eclectus merge utilities
  2. Copyright (C) 1992-96 Eclectus (D. John Anderson, Alan B. Harper).
  3.  
  4. Eclectus merge utilities are free software; you can redistribute
  5. them and/or modify them under the terms of the GNU General Public License
  6. as published by the Free Software Foundation; either version 1, or
  7. (at your option) any later version.
  8.  
  9. Eclectus merge utilities are distributed in the hope that they
  10. will be useful, but WITHOUT ANY WARRANTY; without even the implied
  11. warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  12. See the GNU General Public License for more details.
  13.  
  14. You should have received a copy of the GNU General Public License
  15. along with the Eclectus merge utilities; see the file COPYING.
  16. If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge,
  17. MA 02139, USA.
  18.  
  19. This version was released on Wednesday, September 25, 1996.
  20.  
  21. These 3 utilities--Merge, Difference, and Undifference--make it easy
  22. for many developers to work on the same code base.
  23.  
  24. Start with a complete copy of your source code. This copy is called
  25. the base, which for this example we'll assume is in the directory
  26. tree named EC-0. We write-protect all the files in EC-0 and put it
  27. in a public place. Each developer makes a personal write-enabled
  28. copy of EC-0, named EC on their own machine. They make all their changes
  29. to their personal copy. When everyone agrees that their changes are
  30. ready to merge into a new base we use Merge to merge each
  31. derived copy into EC-0 and create a new base called EC-1, which
  32. everyone copies and development continues.
  33.  
  34. This has an advantage over the traditional "check-in/check-out"
  35. approach in that more than on person can modify a file at the same time.
  36. I was introduced to this approach by Mike Demony who developed it at
  37. MIPS and later promoted it at NeXT. Our experience during the last
  38. 10 years convinced me that it is much more efficient that the traditional
  39. approach, especially in the early stages of development. It also has
  40. the advantage of using the file system for storing the files.
  41.  
  42. There are two other programs, Difference and Undifference, that store
  43. only the changes between two source trees (e.g. EC-0 and EC-1). We
  44. use these programs to store successive versions in a more compact form.
  45. It can also be used to easily exchange versions across different platforms
  46. (e.g. Windows, Macintosh and NeXT). You may find them useful for bringing
  47. copies of your project home on a floppy or emailing your source to a
  48. co-worker who already has a copy of the base.
  49.  
  50. These programs have been used extensively on Macintosh and Windows for many
  51. years.
  52.  
  53. They currently run on Windows NT, Macintosh and NeXT. They are small
  54. which makes them easy to maintain and fast to execute. They can easily
  55. be ported to other environments.
  56.  
  57. The distribution contains release executables, debugging executables, and 
  58. source code for building the release executables.
  59.  
  60. Release versions for Windows are:
  61.     WinTools\Difference.exe
  62.     WinTools\Merge.exe
  63.     WinTools\Undifference.exe
  64.  
  65. Debug versons are:
  66.     WinTools\DifferenceDebug.exe
  67.     WinTools\MergeDebug.exe
  68.     WinTools\UndifferenceDebug.exe
  69.  
  70. Release versions for Macintosh are:
  71.     :MacTools:Difference.mpw
  72.     :MacTools:Merge.mpw
  73.     :MacTools:Undifference.mpw
  74.  
  75. Debug versions are:
  76.     :MacTools:DifferenceDebug.mpw
  77.     :MacTools:MergeDebug.mpw
  78.     :MacTools:UndifferenceDebug.mpw
  79.  
  80. Note--we use the ".mpw" file extension on the MPW tools so that the difference
  81. tools on other platforms can recognize the tools as binary files. You can
  82. rename these files and remove the file extension when you copy the tools to your
  83. "Tools" or "User Commands" directory in your MPW folder.
  84.  
  85. Recent versions of these tools can be found at
  86.   ftp://ftp.dnai.com/users/aharper/EclectusMergeUtilities
  87.  
  88. To compile the release versions on Microsoft Visual C++ 4.1
  89. open the project files
  90.  
  91. WinDifference.mdp
  92. WinMerge.mdp
  93. WinUndifference.mdp
  94.  
  95. and build. The release versions of the executables are created:
  96.     DifferenceR.i/Difference
  97.     MergeR.i/Merge
  98.     UndifferenceR.i/Undifference
  99. The debugging versions won't build in this release because source code for
  100. heap debugging routines are not included. The debugging executables, are 
  101. however, supplied.
  102.  
  103. To compile the release versions under MPW as supplied on the CW10 Gold disk
  104. from Metrowerks execute first:
  105.  
  106. make -f MacMerge.make clean
  107. make -f MacDifference.make clean
  108. make -f MacUndifference.make clean
  109.  
  110. then execute:
  111.  
  112. make -f MacMerge.make
  113. make -f MacDifference.make
  114. make -f MacUndifference.make
  115.  
  116. Three files are created:
  117.     :DifferenceR.i:Difference
  118.     :MergeR.i:Merge
  119.     :UndifferenceR.i:Undifference
  120.  
  121. (Note--a standard install from the CW10 Tools disk does not place the interface files 
  122. and libraries in the expected directories. You will need to copy the
  123. appropriate .h files to MWCIncludes and the appropriate libraries to MW68KLibraries
  124. and MWPPCLibraries. See the install instructions on the CW10 disk.)
  125.  
  126. To compile under the Metrowerks CW10 integrated environment, use the projects
  127. in the "Metrowerks Folder" folder. To make 68K tools, open each of the projects
  128. Difference68K.mwk, Merge68K.mwk, and Undifference68K.mwk and bring them up to date.
  129. Rename the resulting tools by deleting the ".68K" extension. To make PowerPC native tools,
  130. open the "...PPC.mwk" files, bring them up to date, and delete the ".PPC" extension
  131. from the names of the resulting tools. To make fat tools, first make the 68K tools,
  132. but don't rename them. Then bring the "...FAT.mwk" files up to date. Note, only MPW
  133. Shell 3.4d1 and later or ToolServer 3.4d1 or later will use the PowerPC code in a
  134. fat MPW tool. Older versions of MPW will execute the 68K code in emulation.
  135.  
  136. To compile on Next:
  137.  
  138. make -f NextMerge.make clean
  139. make -f NextMerge.make
  140. make -f NextDifference.make clean
  141. make -f NextDifference.make
  142. make -f NextUndifference.make clean
  143. make -f NextUndifference.make
  144.  
  145. 3 files are created:
  146. DerivedDifference.i/Difference
  147. DerivedUndifference.i/Undifference
  148. DerivedMerge.i/Merge
  149.  
  150. usage: Difference SourcePath DestinationPath >DifferenceScriptFile
  151.  
  152. Produces on stdout a file that stores the changes in the files in the tree DestinationPath
  153. that are not in SourcePath. This is useful for backups, storing smaller copies of modified
  154. file trees and beaming changes in file trees through a slow wire. Note: on Macintosh
  155. the SourcePath and DestinationPath must either be fully qualified paths (starting with
  156. the name of a disk), or must start with a ":".
  157.  
  158. Any file or directory name (except those listed on the command line) beginning with "." is
  159. ignored. In addition there is a list of extensions for files and directories that are ignored.
  160. They currently include:
  161.  
  162. i, idb, ilk, ncb, obj, pch, pdb, and tmp
  163.  
  164. Like the binary names extensions below this list can easily be updated by modifying
  165. ignoreExtensions near the top of io.c
  166.  
  167. Binary files are stored in ASCII (hexidecimal) and are not stored as differences, i.e.
  168. they take as much space as the hexidecimal representation of the file. Binary files
  169. are those that don't have a 'TEXT' type on Macintosh or have one of the following
  170. extensions on other machines:
  171.  
  172. aps, bmp, bsc, dll, exe, hlp, ico, ink, lib, mdp, mpw, mwk, ncb, obj, os, osx, pch, 
  173. pdb, prj, res, sbr, scr, vcp, wri, 8bf
  174.  
  175. You can easily change this list by modifying binaryExtensions near the top of io.c. Sometimes
  176. the code gets edited and someone forgets to update this README file with a file extension, so
  177. if you might want to double check the code.
  178.  
  179. If your difference files get large because of many binary files you can compress them to
  180. achieve considerable savings of space; we often get 80% compression using StuffIt.
  181.  
  182. usage: Undifference SourcePath DifferenceScriptFile DestinationPath
  183.  
  184. Recreates DestinationPath out of DifferenceScriptFile and SourcePath.
  185.  
  186. You can think of Difference and Undifference the same way you think of a compression
  187. program. Both programs are designed to work on text files that are line oriented (e.g.
  188. changes are stored as a set of line oriented editing changes). They also work on
  189. binary files, but they don't save any space since the files are stored in ASCII. A
  190. 32 bit hash calculated when Undifference reconstructs a tree ensures that the result is
  191. correct. If a file is unchanged by the difference script when it is Undifferenced,
  192. the data is set to the original date. Execute permission is set if the source file
  193. has execute permission. This is useful for scripts. On Macintosh the resource fork
  194. is taken from the file in the SourcePath if one exists.
  195.  
  196. Difference and Undifference can also be used to transfer entire directory trees from
  197. one platform to another. To do this, difference the tree against an empty directory.
  198. This creates a text file which you can transfer to another platform. Change the end-of-line
  199. character to match the character expected by that platform and then undifference
  200. against an empty directory. The resulting directory will have identical binary files
  201. as the source, and text files will be the same except for the end of line characters.
  202.  
  203. usage: Merge [-c] basePath modification1Path [modification2Path] ... destinationPath
  204.  -c shows all changes even if no collisions occur
  205.  
  206. Merges all changes in the files contained in modification1Path, [modification2Path], ...
  207. that have been made to basePath into the new path destinationPath. Changes are
  208. automatically merged. If two or more people change the same lines a collision occurs
  209. and all changes are listed separately in the merged file. The merged file is renamed
  210. by prepending a "!" to the name so you can easily find files that contain collisions.
  211. If you choose the "-c" option all changes are listed as collisions, which may be useful
  212. if you want to review all the changes. Almost nobody uses the -c option.
  213.  
  214. If binary files differ you must merge them by hand. When they differ they are
  215. listed as !1File, !2File, !3File, ... Each corresponds to the respective modification
  216. path on the command line. Files which occur in more than one derived path (and
  217. which differ) but do not occur in the base path are also listed as
  218. !1File, !2File, !3File, ... and need to be integrated by hand.
  219.  
  220. The message "ADDED" indicates that a file has been added in one of the derived paths. The
  221. message "REMOVED" indicates that a file has been removed from one of the derived paths.
  222. This is useful to help find garbage files that sometimes don't get removed from a source tree
  223. before a merge.
  224.  
  225. Files that are not modified during the merge have the same date as the original date.
  226. The resouce fork on Macintosh is taken from the copy in the basePath.
  227.  
  228. Mac and Next have targets in their make files which include debug, install, test and testDebug.
  229. debug refers to files not included. These files were used to test the memory allocation
  230. to make sure there were no memory leaks, free blocks weren't used, only the contents
  231. of blocks were used, plus zillions of other constency checks. install is used for our
  232. purposes, you should install the tools by hand. test does some simple tests. testDebug does
  233. the same thing as test but with additional tests for the debug versions.
  234.  
  235. On Windows rather than adding targets to the makefile, there is a batch script
  236. "WinMergeTest.bat" that does testing.
  237.  
  238. On the Macintosh, the output from a successful "make -f macmerge.make test" is:
  239.  
  240. COLLISION                        :MergeR.i:testfile.out
  241. File #1: :MergeR.i:!testfile.out
  242. File #2: testfile.merge
  243.  
  244. *** Files match ***
  245.            ADDED    BINARY FILE  :MergeR.i:testd.out:AllChars.OS
  246.            REMOVED  BINARY FILE  :MergeR.i:testd.out:BinaryFile.OS
  247. COLLISION  ADDED    BINARY FILE  :MergeR.i:testd.out:BinaryFile1.OS
  248.            REMOVED  BINARY FILE  :MergeR.i:testd.out:BinaryFile3.OS
  249.            ADDED                 :MergeR.i:testd.out:FileToAdd
  250.            REMOVED               :MergeR.i:testd.out:FileToRemove
  251.            REMOVED  BINARY FILE  :MergeR.i:testd.out:FileToRemove.OS
  252. COLLISION                        :MergeR.i:testd.out:testa
  253. COLLISION                        :MergeR.i:testd.out:testb
  254. COLLISION                        :MergeR.i:testd.out:testc
  255. COLLISION                        :MergeR.i:testd.out:testd
  256.            ADDED                 :MergeR.i:testd.out:testd3d0:testa
  257.            ADDED                 :MergeR.i:testd.out:testd3d0:testb
  258.            ADDED                 :MergeR.i:testd.out:testd3d0:testc
  259.            ADDED                 :MergeR.i:testd.out:testd3d0:testd
  260.                 BINARY FILE  :testd.mac.merge:!1BinaryFile1.OS
  261.                 BINARY FILE  :testd.mac.merge:!2BinaryFile1.OS
  262.                              :testd.mac.merge:!testa
  263.                              :testd.mac.merge:!testb
  264.                              :testd.mac.merge:!testc
  265.                              :testd.mac.merge:!testd
  266.                 BINARY FILE  :testd.mac.merge:AllChars.OS
  267.                              :testd.mac.merge:FileToAdd
  268.                              :testd.mac.merge:testd3d0:testa
  269.                              :testd.mac.merge:testd3d0:testb
  270.                              :testd.mac.merge:testd3d0:testc
  271.                              :testd.mac.merge:testd3d0:testd
  272. No difference between file(s).
  273.  
  274. Limitations
  275.  
  276. The utilities use the standard C library calls to manage files. These calls currently
  277. limit the length of a file path to 255 characters on Macintosh. This can cause problems
  278. if your project has deeply nested directories and long names.
  279.  
  280. Report bugs to aharper@dnai.com or jander@c2.org
  281.  
  282. The Eclectus merge utilities were written by D. John Anderson who is available at:
  283.  
  284. jander@c2.org
  285.  
  286. Eclectus Software
  287. 11 Embarcadero West, Suite 120
  288. Oakland, CA 94607
  289. 510-444-6605 or 415-747-9609
  290.  
  291. The vast majority of code was derived with little or no modification
  292. from GNU diff. GNU diff was written by Mike Haertel, David Hayes,
  293. Richard Stallman, Len Tower and Paul Eggert. The basic algorithm is
  294. described in: "An O(ND) Difference Algorithm and its Variations",
  295. Eugene Myers, Algorithmica Vol. 1 No. 2, 1986, p 251
  296.